Asynchronous Notification

Overview

When a merchant payment to a bank card has a result, PayBy sends the related result to the merchant.

The merchant needs to receive and process the notification, then return a response. The actual arrival time depends on the settlement time of each bank and is subject to the actual arrival time.

Notification Handling Guidelines

1. Duplicate Notifications
   PayBy may send the same notification multiple times. The merchant system must be capable of identifying and handling duplicate notifications correctly to avoid processing the same transaction more than once.

2. Notification Retry Mechanism
   If PayBy receives an invalid response or no response (timeout) from the merchant system during backend notification, it will consider the attempt failed and retry the notification.

   • Retry Policy: Up to 7 attempts
   • Retry Intervals: 2, 10, 10, 60, 120, 360, and 900 minutes

   Note: PayBy does not guarantee final delivery success.

3. Unclear Order Status
   If the payment result is not received or the order status is unclear, merchants are advised to actively query the order status using the transfer query interface.

4. Signature Verification
   All notification requests are signed using PayBy’s RSA private key.

   • The signature algorithm is the same as for ordinary requests.
   • Merchants must verify the signature using PayBy’s public key, which can be downloaded from the merchant portal.

Notification Parameters

The notification request format is the same as ordinary requests, using the HTTP protocol with HTTP headers and a JSON object in the HTTP body.

• transferBankCardOrder TransferBankCardOrder Required
  • Contains the details of the bank card transfer order.

Attributes

• requestTime Timestamp(3) Required

  • Request time passed by the merchant when placing the order.
  • Example value: 1581493898000

• merchantOrderNo String(64) Required

  • Merchant's reference number for tracking the request.
  • Example value: S10000

• orderNo String(32) Required

  • PayBy's unique identification number of the order.
  • Example value: O1000

• product String(200) Required

  • Product name of the API method used in the order.
  • Example value: Transfer Bank Card

• status String Required

  • Status of the order.
  • Possible values: CREATED, SUCCESS, FAILURE, BANK_FAIL

• amount Money Required

  • Amount to be transferred.

• accountHolderType String(16) Required

  • Account holder type: INDIVIDUAL or CORPORATE
  • Example value: INDIVIDUAL

• firstName String(200)

  • SHA256 of original text. Required if accountHolderType is INDIVIDUAL.

• lastName String(200)

  • SHA256 of original text. Required if accountHolderType is INDIVIDUAL.

• middleName String(200)

  • SHA256 of original text.

• companyName String(200)

  • SHA256 of original text. Required if accountHolderType is CORPORATE.

• cardNumber String(64) Required

  • SHA256 of original card number.

• expiryMonth String(2) Required

  • Card expiration month (1–12).
  • Example value: 09

• expiryYear String(4) Required

  • Card expiration year.
  • Example value: 2027

• memo String(128)

  • Transfer description or note.
  • Example value: Bonus

• notifyUrl String(200)

  • URL where the merchant receives notifications.
  • Example value: http://yoursite.com/api/notification

• failDes String(200)

  • Cause of order failure.
  • Example value: -

• bankReference String(128)

  • Bank reference number.

• payerFeeAmount Money Required

  • Fee paid by the payer.
  • Example value:
    {
      "amount": 0,
      "currency": "AED"
    }

• payerFeeMemberId String(32) Required

  • ID of the party paying the fee.
  • Example value: 200000429066

• paidTime Date Required

  • Time of deduction.

• refundedTime Date

  • Time of refund.

Notification Sample

{
  "transferBankCardOrder": {
    // Transfer bank card order details will be provided here
  }
}

Response Parameters

After the merchant receives the notification, return "SUCCESS" to indicate successful receipt.

Any other response indicates an exception.

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success	-
400	INVALID_PARAMETER	Parameter error	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too early compared to current time	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too late compared to current time	Adjust request time
402	RATE_LIMIT_REJECT	Request too frequent	Reduce request frequency
403	UNAUTHORIZED	API unauthorized	Contact PayBy
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy
500	SYSTEM_ERROR	System error	Contact PayBy, retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk control verification failed	Please adjust business
62002	ORDER_FAILURE	Failed order initiated cancellation again. Failed order initiated refund.	Adjust merchant order number
62004	MERCHANT_ORDER_NO_NOT_EXIST	Order with merchant order number does not exist	Adjust merchant order number
62016	MERCHANT_ORDER_NO_EXIST	Same order number, different business parameter order creation request	Adjust order number
62026	PRODUCT_IS_NOT_APPLIED	Product not applied	Please apply for product
62028	ORDER_SUCCESS	Order already successful	Adjust merchant order number
62029	ORDER_CREATED	Order already created	Adjust merchant order number